Sourced from jni's releases.

Rust JNI 0.21.0

While the last (0.20) release was rather conservative (just focusing on reviving the project), this release tackles some more substantial issues (including several safety issues and some bugs dating back to 2018) and as a result it was also necessary to make some breaking changes that will involve some work when updating existing jni code.

Please see the migration guide for some guidance on how to update to this release.

Added

• JavaStr::into_raw() which drops the JavaStr and releases ownership of the raw string pointer (#374)
• JavaStr::from_raw() which takes ownership of a raw string pointer to create a JavaStr (#374)
• JNIEnv::get_string_unchecked is a cheaper, unsafe alternative to get_string that doesn't check the given object is a java.lang.String instance. (#328)
• WeakRef and JNIEnv#new_weak_ref. (#304)
• define_class_bytearray method that takes an AutoElements<jbyte> rather than a &[u8] (#244)
• JObject now has an as_raw method that borrows the JObject instead of taking ownership like into_raw. Needed because JObject no longer has the Copy trait. (#392)
• JavaVM::destroy() (unsafe) as a way to try and unload a JavaVM on supported platforms (#391)
• JavaVM::detach_current_thread() (unsafe) as a way to explicitly detach a thread (normally this is automatic on thread exit). Needed to detach daemon threads manually if using JavaVM::destroy() (#391)
• JPrimitiveArray<T: TypeArray> and type-specific aliases like JByteArray, JIntArray etc now provide safe, reference wrappers for the sys types jarray and jbyteArray etc with a lifetime like JObject (#400)
• JObjectArray provides a reference wrapper for a jobjectArray with a lifetime like JObject. (#400)
• AutoElements and AutoElementsCritical (previously AutoArray/AutoPrimitiveArray) implement Deref<Target=[T]> and DerefMut so array elements can be accessed via slices without needing additional unsafe code. (#400)
• AsJArrayRaw trait which enables JNIEnv::get_array_length() to work with JPrimitiveArray or JObjectArray types (#400)
• InitArgsBuilder now has try_option and option_encoded methods. (#414)

Changed

• JNIEnv::get_string checks that the given object is a java.lang.String instance to avoid undefined behaviour from the JNI implementation potentially aborting the program. (#328)
• JNIEnv::call_*method_unchecked was marked unsafe, as passing improper argument types, or a bad number of arguments, can cause a JVM crash. (#385)
• The JNIEnv::new_object_unchecked function now takes arguments as &[jni::sys::jvalue] to avoid allocating, putting it inline with changes to JniEnv::call_*_unchecked from 0.20.0 (#382)
• The get_superclass function now returns an Option instead of a null pointer if the class has no superclass (#151)
• The invocation feature now locates the JVM implementation dynamically at runtime (via the java-locator crate by default) instead of linking with the JVM at build time (#293)
• Most JNIEnv methods now require &mut self. This improves safety by preventing JObjects from getting an invalid lifetime. Most native method implementations (that is, #[no_mangle] extern "system" fns) must now make the JNIEnv parameter mut. See the example on the crate documentation. (#392)
• JByteBuffer, JClass, JNIEnv, JObject, JString, and JThrowable no longer have the Clone or Copy traits. This improves safety by preventing object references from being used after the JVM deletes them. Most functions that take one of these types as a parameter (except extern fns that are directly called by the JVM) should now borrow it instead, e.g. &JObject instead of JObject. (#392)
• AutoLocal is now generic in the type of object reference (JString, etc). (#392)
• The closure passed to JNIEnv::with_local_frame must now take a &mut JNIEnv parameter, which has a different lifetime. This improves safety by preventing local references from escaping the closure, which would cause a use-after-free bug. Executor::with_attached and Executor::with_attached_capacity have been similarly changed. (#392)
• The closure passed to JNIEnv::with_local_frame can now return a generic Result<T, E> so long as the error implements From<jni::errors::Error> (#399)
• JNIEnv::with_local_frame now returns the same type that the given closure returns (#399)
• JNIEnv::with_local_frame no longer supports returning a local reference directly to the calling scope (see with_local_frame_returning_local) (#399)
• Executor::with_attached and Executor::with_attached_capacity have been changed in the same way as JNIEnv::with_local_frame (they are thin wrappers) (#399)
• Desc, JNIEnv::pop_local_frame, and TypeArray are now unsafe. (#392)
• The Desc trait now has an associated type Output. Many implementations now return AutoLocal, so if you call Desc::lookup yourself and then call as_raw on the returned object, make sure the AutoLocal isn't dropped too soon (see the Desc::lookup documentation for examples). (#392)
• The Desc<JClass> trait is no longer implemented for JObject or &JObject. The previous implementation that called .get_object_class() was surprising and a simpler cast would make it easy to mistakenly pass instances where a class is required. (#118)
• Named lifetimes in the documentation have more descriptive names (like 'local instead of 'a). The new naming convention is explained in the JNIEnv documentation. (#392)
• Object reference types (JObject, JClass, AutoLocal, GlobalRef, etc) now implement AsRef<JObject> and Deref<Target = JObject>. Typed wrappers like JClass also implement Into<JObject>, but GlobalRef does not. (#392)
• Most JList and JMap methods now require a &mut JNIEnv parameter. JListIter and JMapIter no longer implement Iterator, and instead have a next method that requires a &mut JNIEnv parameter (use while let loops instead of for). (#392)
• JValue has been changed in several ways: (#392)
  • It is now a generic type named JValueGen. JValue is now a type alias for JValueGen<&JObject>, that is, it borrows an object reference. JValueOwned is a type alias for JValueGen<JObject>, that is, it owns an object reference.
  • JValueOwned does not have the Copy trait.
  • The to_jni method is now named as_jni, and it borrows the JValueGen instead of taking ownership.
  • JObject can no longer be converted directly to JValue, which was commonly done when calling Java methods or constructors. Instead of obj.into(), use (&obj).into().
• All JNIEnv array APIs now work in terms of JPrimitiveArray and JObjectArray (reference wrappers with a lifetime) instead of sys types like jarray and jbyteArray (#400)
• AutoArray and AutoPrimitiveArray have been renamed AutoElements and AutoElementsCritical to show their connection and differentiate from new JPrimitiveArray API (#400)
• get_primitive_array_critical is now unsafe and has been renamed to get_array_elements_critical (consistent with the rename of AutoPrimitiveArray) with more detailed safety documentation (#400)
• get_array_elements is now also unsafe (for many of the same reasons as get_array_elements_critical) and has detailed safety documentation (#400)
• AutoArray/AutoArrayCritical::size() has been replaced with .len() which can't fail and returns a usize (#400)

... (truncated)

Sourced from jni's changelog.

[0.21.0] — 2023-02-13

This release makes extensive breaking changes in order to improve safety. Most projects that use this library will need to be changed. Please see the migration guide.

Added

• JavaStr::into_raw() which drops the JavaStr and releases ownership of the raw string pointer (#374)
• JavaStr::from_raw() which takes ownership of a raw string pointer to create a JavaStr (#374)
• JNIEnv::get_string_unchecked is a cheaper, unsafe alternative to get_string that doesn't check the given object is a java.lang.String instance. (#328)
• WeakRef and JNIEnv#new_weak_ref. (#304)
• define_class_bytearray method that takes an AutoElements<jbyte> rather than a &[u8] (#244)
• JObject now has an as_raw method that borrows the JObject instead of taking ownership like into_raw. Needed because JObject no longer has the Copy trait. (#392)
• JavaVM::destroy() (unsafe) as a way to try and unload a JavaVM on supported platforms (#391)
• JavaVM::detach_current_thread() (unsafe) as a way to explicitly detach a thread (normally this is automatic on thread exit). Needed to detach daemon threads manually if using JavaVM::destroy() (#391)
• JPrimitiveArray<T: TypeArray> and type-specific aliases like JByteArray, JIntArray etc now provide safe, reference wrappers for the sys types jarray and jbyteArray etc with a lifetime like JObject (#400)
• JObjectArray provides a reference wrapper for a jobjectArray with a lifetime like JObject. (#400)
• AutoElements and AutoElementsCritical (previously AutoArray/AutoPrimitiveArray) implement Deref<Target=[T]> and DerefMut so array elements can be accessed via slices without needing additional unsafe code. (#400)
• AsJArrayRaw trait which enables JNIEnv::get_array_length() to work with JPrimitiveArray or JObjectArray types (#400)
• InitArgsBuilder now has try_option and option_encoded methods. (#414)

Changed

• JNIEnv::get_string checks that the given object is a java.lang.String instance to avoid undefined behaviour from the JNI implementation potentially aborting the program. (#328)
• JNIEnv::call_*method_unchecked was marked unsafe, as passing improper argument types, or a bad number of arguments, can cause a JVM crash. (#385)
• The JNIEnv::new_object_unchecked function now takes arguments as &[jni::sys::jvalue] to avoid allocating, putting it inline with changes to JniEnv::call_*_unchecked from 0.20.0 (#382)
• The get_superclass function now returns an Option instead of a null pointer if the class has no superclass (#151)
• The invocation feature now locates the JVM implementation dynamically at runtime (via the java-locator crate by default) instead of linking with the JVM at build time (#293)
• Most JNIEnv methods now require &mut self. This improves safety by preventing JObjects from getting an invalid lifetime. Most native method implementations (that is, #[no_mangle] extern "system" fns) must now make the JNIEnv parameter mut. See the example on the crate documentation. (#392)
• JByteBuffer, JClass, JNIEnv, JObject, JString, and JThrowable no longer have the Clone or Copy traits. This improves safety by preventing object references from being used after the JVM deletes them. Most functions that take one of these types as a parameter (except extern fns that are directly called by the JVM) should now borrow it instead, e.g. &JObject instead of JObject. (#392)
• AutoLocal is now generic in the type of object reference (JString, etc). (#392)
• The closure passed to JNIEnv::with_local_frame must now take a &mut JNIEnv parameter, which has a different lifetime. This improves safety by preventing local references from escaping the closure, which would cause a use-after-free bug. Executor::with_attached and Executor::with_attached_capacity have been similarly changed. (#392)
• The closure passed to JNIEnv::with_local_frame can now return a generic Result<T, E> so long as the error implements From<jni::errors::Error> (#399)
• JNIEnv::with_local_frame now returns the same type that the given closure returns (#399)
• JNIEnv::with_local_frame no longer supports returning a local reference directly to the calling scope (see with_local_frame_returning_local) (#399)
• Executor::with_attached and Executor::with_attached_capacity have been changed in the same way as JNIEnv::with_local_frame (they are thin wrappers) (#399)
• Desc, JNIEnv::pop_local_frame, and TypeArray are now unsafe. (#392)
• The Desc trait now has an associated type Output. Many implementations now return AutoLocal, so if you call Desc::lookup yourself and then call as_raw on the returned object, make sure the AutoLocal isn't dropped too soon (see the Desc::lookup documentation for examples). (#392)
• The Desc<JClass> trait is no longer implemented for JObject or &JObject. The previous implementation that called .get_object_class() was surprising and a simpler cast would make it easy to mistakenly pass instances where a class is required. (#118)
• Named lifetimes in the documentation have more descriptive names (like 'local instead of 'a). The new naming convention is explained in the JNIEnv documentation. (#392)
• Object reference types (JObject, JClass, AutoLocal, GlobalRef, etc) now implement AsRef<JObject> and Deref<Target = JObject>. Typed wrappers like JClass also implement Into<JObject>, but GlobalRef does not. (#392)
• Most JList and JMap methods now require a &mut JNIEnv parameter. JListIter and JMapIter no longer implement Iterator, and instead have a next method that requires a &mut JNIEnv parameter (use while let loops instead of for). (#392)
• JValue has been changed in several ways: (#392)
  • It is now a generic type named JValueGen. JValue is now a type alias for JValueGen<&JObject>, that is, it borrows an object reference. JValueOwned is a type alias for JValueGen<JObject>, that is, it owns an object reference.
  • JValueOwned does not have the Copy trait.
  • The to_jni method is now named as_jni, and it borrows the JValueGen instead of taking ownership.
  • JObject can no longer be converted directly to JValue, which was commonly done when calling Java methods or constructors. Instead of obj.into(), use (&obj).into().
• All JNIEnv array APIs now work in terms of JPrimitiveArray and JObjectArray (reference wrappers with a lifetime) instead of sys types like jarray and jbyteArray (#400)
• AutoArray and AutoPrimitiveArray have been renamed AutoElements and AutoElementsCritical to show their connection and differentiate from new JPrimitiveArray API (#400)
• get_primitive_array_critical is now unsafe and has been renamed to get_array_elements_critical (consistent with the rename of AutoPrimitiveArray) with more detailed safety documentation (#400)
• get_array_elements is now also unsafe (for many of the same reasons as get_array_elements_critical) and has detailed safety documentation (#400)
• AutoArray/AutoArrayCritical::size() has been replaced with .len() which can't fail and returns a usize (#400)
• The TypeArray trait is now a private / sealed trait, that is considered to be an implementation detail for the AutoArray API.

... (truncated)

• 5099f42 Merge pull request #415 from rib/release-0.21
• c641cf8 Release 0.21.0
• a0c4c48 Merge pull request #414 from argv-minus-one/invocation-character-encoding
• 61d1e2c Properly encode JVM options on Windows.
• 3066408 Merge pull request #412 from rib/no-jclass-desc-for-jobject
• fe30084 Adds call_new_object_with_array_class() test
• 1d82678 Remove Desc<JClass> implementation for JObject and &JObject
• 6690b6c Merge pull request #400 from rib/array-wrapper-types
• df94446 Clarify in the changelog and 0.21 migration guide that getting an `AutoElemen...
• ed6dba3 Add missing unsafe to an example in the 0.21 migration guide.
• Additional commits viewable in compare view

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot merge will merge this PR after your CI passes on it
• @dependabot squash and merge will squash and merge this PR after your CI passes on it
• @dependabot cancel merge will cancel a previously requested merge and block automerging
• @dependabot reopen will reopen this PR if it is closed
• @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)